=begin pod

=TITLE class Rat

=SUBTITLE Rational number (limited-precision)

    class Rat is Cool does Rational[Int, uint64] { }

C<Rat> objects store rational numbers as a pair of a numerator and
denominator. Number literals with a dot but without exponent produce
C<Rat>s.

    3.1;    # Rat.new(31, 10)
    <1/2>   # Rat.new(1, 2)

Thus arithmetic with short dotted-decimal numbers does not suffer
from floating point errors.

To prevent the numerator and denominator from becoming pathologically large,
the denominator is limited to 64 bit storage. On overflow of the denominator
a C<Num> (floating-point number) is returned instead.

For example this function crudely approximates a square root, and overflows
the denominator quickly:

    sub approx-sqrt($n, $iterations) {
        my $x = $n;
        $x = ($x + $n / $x) / 2 for ^$iterations;
        return $x;
    }
    say approx-sqrt(2, 5).^name;     # OUTPUT: «Rat␤»
    say approx-sqrt(2, 10).^name;    # OUTPUT: «Num␤»

If you want arbitrary precision arithmetic with rational numbers, use the
L<FatRat|/type/FatRat> type instead.

C<Rat> objects are immutable.

=head1 Methods

=head2 method perl

    multi method perl(Rat:D: --> Str:D)

Returns a string representation corresponding to the unambiguous
C<val()>-based representation of rational literals.  If the
number can be represented exactly in decimal, it will be. Otherwise uses
the form "C<< <3/5> >>", without internal spaces, and including the
angles that keep the C</> from being treated as a normal division
operator.

    say (1/3).perl;                # OUTPUT: «<1/3>␤»
    say (2/4).perl;                # OUTPUT: «0.5␤»

=end pod

# vim: expandtab softtabstop=4 shiftwidth=4 ft=perl6
